<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Library.BrightSword.CommandLineUtilities</name>
    </assembly>
    <members>
        <member name="T:BrightSword.CommandLineUtilities.CommandLineParameterException">
            <summary>
              Throw an instance of this, or a derived, exception to signal the unsuitability of a user-supplied command line parameter value
            </summary>
        </member>
        <member name="M:BrightSword.CommandLineUtilities.CommandLineParameterException.#ctor(System.String,System.String)">
            <summary>
              Create an instance of this exception to throw
            </summary>
            <param name="parameterName"> The name of the parameter with the unsuitable value </param>
            <param name="message"> Helpful text which will be displayed in the error message </param>
        </member>
        <member name="T:BrightSword.CommandLineUtilities.CommandLineApplication">
            <summary>
              A static container for command-line processing extension methods.
            </summary>
        </member>
        <member name="M:BrightSword.CommandLineUtilities.CommandLineApplication.Run``2(``0,System.String[],System.Func{``1,System.Int32})">
            <summary>
              A generic extension method to automatically process command line parameters and provide a strongly-typed form to a specified processing function
            </summary>
            <typeparam name="TCallSite"> The type of the program which needs to process command-line arguments. Typically this class has a function of the form <code>internal static int Main(string[] args)
                                                                                                                                                                  {
                                                                                                                                                                  ...
                                                                                                                                                                  }</code> </typeparam>
            <typeparam name="TCommandLineParams"> The strongly typed container which specifies the expected command-line parameters </typeparam>
            <param name="_this"> The running instance of the program class. Used as the 'this' parameter to this method </param>
            <param name="args"> The array of command-line arguments as passed in from the environment </param>
            <param name="action"> The actual function which does the work to be done inside Main, but with reference to strongly-typed parameters instead of <paramref
               name="args" /> </param>
            <returns> The result value of the actual function provided. </returns>
            <example>
              Consider a hypothetical app which requires a few command-line parameters, some optional, and some flags: We can create a type to encapsulate the arguments, and implement the Main function as follows: <code>[CommandLineApplication("A funky application to create the zero-th version of something")]
                                                                                                                                                                                                                        internal class Parameters
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        [CommandLineArgument("database", "The full path and name of the database")]
                                                                                                                                                                                                                        public string DatabasePath { get; set; }
             
                                                                                                                                                                                                                        [CommandLineArgument("clobber", "Should this database be clobbered", IsFlag = true)]
                                                                                                                                                                                                                        public bool Clobber { get; set; }
             
                                                                                                                                                                                                                        [CommandLineArgument("create", "Should this database be created", true)]
                                                                                                                                                                                                                        public bool Create { get; set; }
                                                                                                                                                                                                                        }
             
                                                                                                                                                                                                                        internal class Program
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        internal static int Main(string[] args)
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        return (new Program()).Run&lt;Program, Parameters&gt;(args, _ => RunAction(_));
                                                                                                                                                                                                                        }
            
                                                                                                                                                                                                                        internal static int RunAction(Parameters parameters)
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        Console.WriteLine(parameters.DatabasePath);
                                                                                                                                                                                                                        return 0;
                                                                                                                                                                                                                        }
                                                                                                                                                                                                                        }</code> Running this: C:/&gt; runprog --database="foo.sdb" foo.sdb Press any key to continue . . . Further, we get two arguments for free: * --help will print the usage parameters and quite * --verbose will print the effective parameters used for execution, and perform the execution C:/&gt; runprog --verbose --database="foo.sdb" --clobber *********************************************************************************************** *** *** runprog.exe - A funky application to create the zero-th version of something *** *** Run Started: 15/07/2011 8:05:20 PM *** *** The effective value of --help is [null] *** The effective value of --verbose is [null] *** The effective value of --database is [foo.sdb] *** The effective value of --clobber is [True] *** The effective value of --create is [True] *** *********************************************************************************************** foo.sdb Press any key to continue . . .
            </example>
        </member>
        <member name="M:BrightSword.CommandLineUtilities.CommandLineApplication.Run``2(``0,System.String[],System.Action{``1})">
            <summary>
              A generic extension method to automatically process command line parameters and provide a strongly-typed form to a specified processing method
            </summary>
            <typeparam name="TCallSite"> The type of the program which needs to process command-line arguments. Typically this class has a function of the form <code>internal static void Main(string[] args)
                                                                                                                                                                  {
                                                                                                                                                                  ...
                                                                                                                                                                  }</code> </typeparam>
            <typeparam name="TCommandLineParams"> The strongly typed container which specifies the expected command-line parameters </typeparam>
            <param name="_this"> The running instance of the program class. Used as the 'this' parameter to this method </param>
            <param name="args"> The array of command-line arguments as passed in from the environment </param>
            <param name="action"> The actual function which does the work to be done inside Main, but with reference to strongly-typed parameters instead of <paramref
               name="args" /> </param>
            <example>
              Consider a hypothetical app which requires a few command-line parameters, some optional, and some flags: We can create a type to encapsulate the arguments, and implement the Main function as follows: <code>[CommandLineApplication("A funky application to create the zero-th version of something")]
                                                                                                                                                                                                                        internal class Parameters
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        [CommandLineArgument("database", "The full path and name of the database")]
                                                                                                                                                                                                                        public string DatabasePath { get; set; }
             
                                                                                                                                                                                                                        [CommandLineArgument("clobber", "Should this database be clobbered", IsFlag = true)]
                                                                                                                                                                                                                        public bool Clobber { get; set; }
             
                                                                                                                                                                                                                        [CommandLineArgument("create", "Should this database be created", true)]
                                                                                                                                                                                                                        public bool Create { get; set; }
                                                                                                                                                                                                                        }
             
                                                                                                                                                                                                                        internal class Program
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        internal static void Main(string[] args)
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        (new Program()).Run&lt;Program, Parameters&gt;(args, _ => RunAction(_));
                                                                                                                                                                                                                        }
            
                                                                                                                                                                                                                        internal static void RunAction(Parameters parameters)
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        Console.WriteLine(parameters.DatabasePath);
                                                                                                                                                                                                                        }
                                                                                                                                                                                                                        }</code> Running this: C:/&gt; runprog --database="foo.sdb" foo.sdb Press any key to continue . . . Further, we get two arguments for free: * --help will print the usage parameters and quite * --verbose will print the effective parameters used for execution, and perform the execution C:/&gt; runprog --verbose --database="foo.sdb" --help *********************************************************************************************** *** *** GenerateVersionZero.exe - A funky application to create the zero-th version of something *** *** Usage: GenerateVersionZero.exe [--help] [--verbose] --database=&lt;value&gt; --clobber [--create] *** *** [--help] : [Optional] Prints this message and quits *** The effective value of --help is [null] *** *** [--verbose] : [Optional] Emits more information *** The effective value of --verbose is [null] *** *** --database=&lt;value&gt; : The full path and name of the database *** The effective value of --database is [null] *** *** --clobber : Should this database be clobbered *** The effective value of --clobber is [False] *** *** [--create] : [Optional] Should this database be created *** --create has a default value of [True] *** The effective value of --create is [True] *** *** *** Ensure that there are no spaces except between arguments. *** Quote values that embed a space. *** Use '--arg=value' and not '--arg = value'. *** *** Exiting... *** *********************************************************************************************** Press any key to continue . . .
            </example>
        </member>
        <member name="M:BrightSword.CommandLineUtilities.CommandLineApplication.Run``1(System.String[],System.Func{``0,System.Int32})">
            <summary>
              A generic method to automatically process command line parameters and provide a strongly-typed form to a specified processing function
            </summary>
            <typeparam name="TCommandLineParams"> The strongly typed container which specifies the expected command-line parameters </typeparam>
            <param name="args"> The array of command-line arguments as passed in from the environment </param>
            <param name="action"> The actual function which does the work to be done inside Main, but with reference to strongly-typed parameters instead of <paramref
               name="args" /> </param>
            <returns> The result value of the actual function provided. </returns>
            <example>
              Consider a hypothetical app which requires a few command-line parameters, some optional, and some flags: We can create a type to encapsulate the arguments, and implement the Main function as follows: <code>[CommandLineApplication("A funky application to create the zero-th version of something")]
                                                                                                                                                                                                                        internal class Parameters : ICommandLineParams
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        [CommandLineArgument("database", "The full path and name of the database")]
                                                                                                                                                                                                                        public string DatabasePath { get; set; }
             
                                                                                                                                                                                                                        [CommandLineArgument("clobber", "Should this database be clobbered", IsFlag = true)]
                                                                                                                                                                                                                        public bool Clobber { get; set; }
             
                                                                                                                                                                                                                        [CommandLineArgument("create", "Should this database be created", true)]
                                                                                                                                                                                                                        public bool Create { get; set; }
                                                                                                                                                                                                                        }
             
                                                                                                                                                                                                                        internal static class Program
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        internal static int Main(string[] args)
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        return Run&lt;Parameters&gt;(args, _ => RunAction(_));
                                                                                                                                                                                                                        }
            
                                                                                                                                                                                                                        internal static void RunAction(Parameters parameters)
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        Console.WriteLine(parameters.DatabasePath);
                                                                                                                                                                                                                        }
                                                                                                                                                                                                                        }</code> Running this: C:/&gt; runprog --database="foo.sdb" foo.sdb Press any key to continue . . . Further, we get two arguments for free: * --help will print the usage parameters and quite * --verbose will print the effective parameters used for execution, and perform the execution C:/&gt; runprog --verbose --database="foo.sdb" --clobber *********************************************************************************************** *** *** runprog.exe - A funky application to create the zero-th version of something *** *** Run Started: 15/07/2011 8:05:20 PM *** *** The effective value of --help is [null] *** The effective value of --verbose is [null] *** The effective value of --database is [foo.sdb] *** The effective value of --clobber is [True] *** The effective value of --create is [True] *** *********************************************************************************************** foo.sdb Press any key to continue . . .
            </example>
        </member>
        <member name="M:BrightSword.CommandLineUtilities.CommandLineApplication.Run``1(System.String[],System.Action{``0})">
            <summary>
              A generic extension method to automatically process command line parameters and provide a strongly-typed form to a specified processing method
            </summary>
            <typeparam name="TCommandLineParams"> The strongly typed container which specifies the expected command-line parameters </typeparam>
            <param name="args"> The array of command-line arguments as passed in from the environment </param>
            <param name="action"> The actual function which does the work to be done inside Main, but with reference to strongly-typed parameters instead of <paramref
               name="args" /> </param>
            <example>
              Consider a hypothetical app which requires a few command-line parameters, some optional, and some flags: We can create a type to encapsulate the arguments, and implement the Main function as follows: <code>[CommandLineApplication("A funky application to create the zero-th version of something")]
                                                                                                                                                                                                                        internal class Parameters
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        [CommandLineArgument("database", "The full path and name of the database")]
                                                                                                                                                                                                                        public string DatabasePath { get; set; }
             
                                                                                                                                                                                                                        [CommandLineArgument("clobber", "Should this database be clobbered", IsFlag = true)]
                                                                                                                                                                                                                        public bool Clobber { get; set; }
             
                                                                                                                                                                                                                        [CommandLineArgument("create", "Should this database be created", true)]
                                                                                                                                                                                                                        public bool Create { get; set; }
                                                                                                                                                                                                                        }
             
                                                                                                                                                                                                                        internal static class Program
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        internal static void Main(string[] args)
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        CommandLineApplication.Run&lt;Parameters&gt;(args, _ => RunAction(_));
                                                                                                                                                                                                                        }
            
                                                                                                                                                                                                                        internal static void RunAction(Parameters parameters)
                                                                                                                                                                                                                        {
                                                                                                                                                                                                                        Console.WriteLine(parameters.DatabasePath);
                                                                                                                                                                                                                        }
                                                                                                                                                                                                                        }</code> Running this: C:/&gt; runprog --database="foo.sdb" foo.sdb Press any key to continue . . . Further, we get two arguments for free: * --help will print the usage parameters and quite * --verbose will print the effective parameters used for execution, and perform the execution C:/&gt; runprog --verbose --database="foo.sdb" --help *********************************************************************************************** *** *** GenerateVersionZero.exe - A funky application to create the zero-th version of something *** *** Usage: GenerateVersionZero.exe [--help] [--verbose] --database=&lt;value&gt; --clobber [--create] *** *** [--help] : [Optional] Prints this message and quits *** The effective value of --help is [null] *** *** [--verbose] : [Optional] Emits more information *** The effective value of --verbose is [null] *** *** --database=&lt;value&gt; : The full path and name of the database *** The effective value of --database is [null] *** *** --clobber : Should this database be clobbered *** The effective value of --clobber is [False] *** *** [--create] : [Optional] Should this database be created *** --create has a default value of [True] *** The effective value of --create is [True] *** *** *** Ensure that there are no spaces except between arguments. *** Quote values that embed a space. *** Use '--arg=value' and not '--arg = value'. *** *** Exiting... *** *********************************************************************************************** Press any key to continue . . .
            </example>
        </member>
        <member name="T:BrightSword.CommandLineUtilities.CommandLineApplicationAttribute">
            <summary>
              Use this attribute to mark up the struct or class which encapsulates the command line parameters of the application.
            </summary>
            <example>
              Consider a hypothetical app which requires a few command-line parameters, some optional, and some flags: We can create a type to encapsulate the arguments as follows: <code>[CommandLineApplication("A funky application to create the zero-th version of something")]
                                                                                                                                                                                       internal class Parameters
                                                                                                                                                                                       {
                                                                                                                                                                                       [CommandLineArgument("database", "The full path and name of the database", false, false)]
                                                                                                                                                                                       public string DatabasePath { get; set; }
            
                                                                                                                                                                                       [CommandLineArgument("clobber", "Should this database be clobbered", true, false)]
                                                                                                                                                                                       public bool Clobber { get; set; }
            
                                                                                                                                                                                       [CommandLineArgument("create", "Should this database be created", true, true, DefaultValue = true)]
                                                                                                                                                                                       public bool Create { get; set; }
                                                                                                                                                                                       }</code> In this example, the short description provided is sufficient to provide friendly diagnostic information
            </example>
        </member>
        <member name="M:BrightSword.CommandLineUtilities.CommandLineApplicationAttribute.#ctor(System.String)">
            <summary>
              Constructor for the attribute with a specified (optional) description.
            </summary>
            <param name="description"> The description of this application. Although optional, if no description is provided, a snarky message is used instead, so provide one! </param>
        </member>
        <member name="P:BrightSword.CommandLineUtilities.CommandLineApplicationAttribute.Description">
            <summary>
              A description for the application. Displayed when --help or --verbose is specified.
            </summary>
        </member>
        <member name="T:BrightSword.CommandLineUtilities.CommandLineArgumentAttribute">
            <summary>
              Use this attribute to mark individual properties on an implementation of ICommandLineParams. This is used to bind command-line parameters provided to individual, strongly-typed properties on the object. This attribute can mark up either properties (suggested usage) or fields (legacy style)
            </summary>
            <example>
              See the individual constructor signatures for specific examples of usage
            </example>
        </member>
        <member name="M:BrightSword.CommandLineUtilities.CommandLineArgumentAttribute.#ctor(System.String,System.String)">
            <summary>
              Specifies the property to be a mandatory command-line argument. When the argument is specified on the command line, the caller must provide an appropriate value for the argument
            </summary>
            <param name="name"> The name of the argument string specified on the command line, without the '--' </param>
            <param name="description"> The description of the argument </param>
            <example>
              <code>[CommandLineArgument("database", "The full path and name of the database")]
                public string DatabasePath { get; set; }</code> will require the application include a command-line argument of the form --database=somevalue If the command-line argument is to be a flag, (i.e without a value specified), use this constructor and provide the named parameter 'IsFlag' <code>[CommandLineArgument("clobber", "Flag argument specifying if the database should be clobbered", IsFlag = true)]
                                                                                                                                                                                                                                                                                                             public bool Clobber { get; set; }</code>
            </example>
        </member>
        <member name="M:BrightSword.CommandLineUtilities.CommandLineArgumentAttribute.#ctor(System.String,System.String,System.Object)">
            <summary>
              Specifies the property to be a (possibly) optional command-line argument. When the argument is specified on the command line, the caller may provide an value for the argument If no argument is specified, the default argument specified here will be applied.
            </summary>
            <param name="name"> The name of the argument string specified on the command line, without the '--' </param>
            <param name="description"> The description of the argument </param>
            <param name="defaultValue"> The default value to be applied if none is specified. Ensure that this value is of the same type of the property the attribute is defined on. If this value is set to 'null', the argument is treated as mandatory. </param>
            <example>
              <code>[CommandLineArgument("exchange_rate", "The exchange rate to apply for the calculation", "1.0")]
                public double ExchangeRate { get; set; }</code> will allow the application to include a command-line argument of the form --exchange_rate=1.1675 However, if no --exchange_rate argument is provided, it is as if --exchange_rate=1.0 was specified. <code>[CommandLineArgument("clobber", "Flag argument specifying if the database should be clobbered", IsFlag = true)]
                                                                                                                                                                                                                                                                       public bool Clobber { get; set; }</code>
            </example>
        </member>
        <member name="P:BrightSword.CommandLineUtilities.CommandLineArgumentAttribute.IsOptional">
            <summary>
              Can be used as a named parameter to specify that the argument is optional
            </summary>
        </member>
        <member name="P:BrightSword.CommandLineUtilities.CommandLineArgumentAttribute.IsFlag">
            <summary>
              Can be used as a named parameter to specify that the argument is a flag and requires no value. Flags are always optional, so setting this to true will also set IsOptional to true.
            </summary>
            <example>
              Use these named parameters with care, as it is possible to create meaningless parameters. Consider: <code>[CommandLineArgument("create", "Should this database be created", true, IsFlag=true)]
                                                                                                                    public bool Create { get; set; }</code> which results in *** [--create] : [Optional] Should this database be created *** --create has a default value of [True] *** The effective value of --create is [True] This effectively means that --create will result in the same behaviour whether it is specified or not!
            </example>
        </member>
    </members>
</doc>
